en:documentation:script_reference

# Script reference

This page contain reference material for scripting functions.

See the Tool Box description page for general information.

See the script example page for a quick start with the programming functions.

## Script language

The language to use is Pascal Script.
For a complete reference of the Object Pascal language your can read the Free Pascal Reference guide. But beware that some feature are not implemented by the script language, for example: no pointer, no assembler, no overloading.

In addition to the standard Pascal Script feature the following Skychart specific function are added.

## Main menu function

Every items of the main menu can be used from the scripts.
The full list of menu items name is available from the menu list.

You can execute the menu action by using the Click method, or test if an option is activated by testing the Checked property.

## Translation string

Every string translated for the main program can be used in a script.
Directly use the rsXXX constant to get the translated string.
The full list of available string is available from the source code.
If a string is not translated for your language don't hesitate to do it yourself.

## Constants

name | value
--- | ---
deg2rad | degree to radian conversion constant
rad2deg | radian to degree conversion constant

## Global variables access

function GetS(varname:string; var str: string):Boolean;
Get the global string variable identified by varname
varname | value
--- | ---
ChartName | The name of the last chart that send an event
RefreshText | The text of the ChartRefresh event
SelectionText | The short text of the selected object
DescriptionText | The object full description
DistanceText | The text of the last distance measurement event
Str1 .. Str10 | Ten global variable for your use

function SetS(varname:string; str: string):Boolean;
Set the global string variable identified by varname for later use
varname | value
--- | ---
Str1 .. Str10 | Ten global variable for your use

function GetSL(varname:string; var strl: Tstringlist):Boolean;
Get the global stringlist variable identified by varname
varname | value
--- | ---
Strl1 .. Strl10 | Ten global variable for your use

function SetSL(varname:string; stlr: Tstringlist):Boolean;
Set the global stringlist variable identified by varname for later use
varname | value
--- | ---
Strl1 .. Strl10 | Ten global variable for your use

function GetI(varname:string; var i: Integer):Boolean;
Get the global integer variable identified by varname
varname | value
--- | ---
Int1 .. Int10 | Ten global variable for your use

function SetI(varname:string; i: Integer):Boolean;
Set the global integer variable identified by varname for later use
varname | value
--- | ---
Int1 .. Int10 | Ten global variable for your use

function GetD(varname:string; var x: double):boolean;
Get the global double variable identified by varname
varname | value
--- | ---
TelescopeRA | The telescope position right ascension
TelescopeDE | The telescope position declination
TimeNow | The current time in TDateTime format
Double1 .. Double10 | Ten global variable for your use

function SetD(varname:string; x: Double):Boolean;
Set the global double variable identified by varname for later use
varname | value
--- | ---
Double1 .. Double10 | Ten global variable for your use

function GetV(varname:string; var v: Variant):Boolean;
Get the global variant variable identified by varname
varname | value
--- | ---
Telescope1 , Telescope2 | Two ASCOM Telescope objects
Dome1 , Dome2 | Two ASCOM Dome objects
Camera1 , Camera2 | Two ASCOM Camera objects
Focuser1 , Focuser2 | Two ASCOM Focuser objects
Filter1 , Filter2 | Two ASCOM Filter wheel objects
Rotator1 , Rotator2 | Two ASCOM Rotator objects
Variant1 .. Variant10 | Ten global variable for your use

function SetV(varname:string; v: Variant):Boolean;
Set the global variant variable identified by varname for later use
varname | value
--- | ---
Telescope1 , Telescope2 | Two ASCOM Telescope objects
Dome1 , Dome2 | Two ASCOM Dome objects
Camera1 , Camera2 | Two ASCOM Camera objects
Focuser1 , Focuser2 | Two ASCOM Focuser objects
Filter1 , Filter2 | Two ASCOM Filter wheel objects
Rotator1 , Rotator2 | Two ASCOM Rotator objects
Variant1 .. Variant10 | Ten global variable for your use

## Chart and Celestial objects

function Cmd(cname:string; arg:Tstringlist):string;
Execute one of the Skychart server command. Add the command name first to the string list, then each parameter.

procedure SendInfo(origin,str:string);
Send a message to the clients connected to the Skychart server.

function GetObservatoryList(list:TstringList):boolean;
Return the list of the Observatory favorite

function GetScopeRates(list:TstringList):boolean;
Return a list of speed rate supported by the telescope

function GetCometList(const filter: string; maxnum:integer; list:TstringList):boolean;
Return a list of comet according to the filter

function GetAsteroidList(const filter: string; maxnum:integer; list:TstringList):boolean;
Return a list of asteroid according to the filter

function CometMark(list:TstringList):boolean;
Mark the listed comet to the chart

function AsteroidMark(list:TstringList):boolean;
Mark the listed asteroid to the chart

## Coordinates conversion

Procedure Eq2Hz(var ra,de : double ; var a,h : double);
Convert Equatorial ra,de to Alt/Az a,h for the location and time of the current chart, all angle in radian

Procedure Hz2Eq(var a,h : double; var ra,de : double);
Convert Alt/Az a,h to equatorial ra,de for the location and time of the current chart, all angle in radian

Procedure Eq2Gal(var ra,de : double ; var l,b : double);
Convert Equatorial ra,de to Galactic l,b , all angle in radian

Procedure Gal2Eq(var l,b : double; var ra,de : double);
Convert Galactic l,b to equatorial ra,de , all angle in radian

Procedure Eq2Ecl(var ra,de : double ; var l,b : double);
Convert Equatorial ra,de to Ecliptic l,b with obliquity for the date of the current chart, all angle in radian

Procedure Ecl2Eq(var l,b : double; var ra,de : double);
Convert Ecliptic l,b to Equatorial ra,de with obliquity for the date of the current chart, all angle in radian

## Formating and conversion

Function ARtoStr(var ar: Double) : string;
Return a string formated Right Ascension of ar value

Function DEtoStr(var de: Double) : string;
Return a string formated Declination of de value

Function StrtoAR(str:string; var ar: Double) : boolean;
Convert a formated string to Right Ascension decimal value

Function StrtoDE(str:string; var de: Double) : boolean;
Convert a formated string to Declination decimal value

Function JDtoStr(var jd: Double) : string;
Format a julian date to YYYY-MM-DD string

Function StrtoJD(dt:string; var jdt: Double) : boolean;
Convert a formated string YYYY-MM-DD to julian date value

Function FormatFloat(Const Format : String; var Value : double) : String;
Format a decimal number according to the Format specification

Function Format(Const Fmt : String; const Args : Array of const) : String;
The Format Pascal function

Procedure StrtoFloatD(str:string; var defval: Double; var val: Double);
Convert a string to a floating point value. Return defval if the string is a invalid number

function IsNumber(str: String): boolean;
Return True if the string represent a valid number

function StringReplace(str,s1,s2: String): string;
Replace all occurrence of s1 by s2 in str

procedure JsonToStringlist(jsontxt:string; var SK,SV: TStringList);
Parse a JSON formated string and return two stringlist. SK contain the names and SV the corresponding values

## Dialog

function OpenDialog(var fn: string): boolean;
The standard Open File dialog. Return True if the OK button is pressed after the file selection.

function SaveDialog(var fn: string): boolean;
The standard Save File dialog. Return True if the OK button is pressed after the file selection.

function MsgBox(const aMsg: string):boolean;
A message confirmation dialog. Return True if YES is clicked.

Procedure ShowMessage(const aMsg: string);
Display a message.

function CalendarDialog(var dt: double): boolean;
The Skychart Calendar dialog. Return dt julian date

## Run external program

function Run(cmdline:string):boolean;
Execute the specified command. Return immediately without waiting for the execution to end.

function RunOutput(cmdline:string; var output:TStringlist):boolean;
Execute the specified command, wait for termination and put the stdout to “output”. Beware this function can completely lock the main program if it not finish in time.

function OpenFile(fn:string):boolean;
Open a document file using the default program

Also see the example about how to call a function in an external library.

## TCP/IP client socket

For all this functions socknum identify the socket to use. This is a number between 1 and 10, thus allowing 10 simultaneous connection to different server.

function TcpConnect(socknum:integer; ipaddr,port,timeout:string):boolean;
Connect to the server at ipaddr:port and set the timeout for the subsequent operations

function TcpDisconnect(socknum:integer):boolean;
Disconnect from the server

Function TcpConnected(socknum:integer) : boolean;
Return True if the socket is connected

Function TcpRead(socknum:integer; var buf : string; termchar:string) : boolean;
Read data from the socket until the character termchar is encountered, typically termchar is CRLF

Function TcpReadCount(socknum:integer; var buf : string; var count : integer) : boolean;
Read data from the socket until count character are read or timeout is reached

Function TcpWrite(socknum:integer; var buf : string; var count : integer) : boolean;
Write data to the socket from buf for a length of count

Procedure TcpPurgeBuffer(socknum:integer);
Purge all the received data currently queued in the receive buffer